第七日：與 Codex 共筆的一天，需求從草圖到工地藍圖

今天真的是個「血肉交織」的日子。昨天還在畫設計圖，今天直接拉著 Codex 這位「程式碼夥伴」進工地裡一起打螺絲。結果不只打完了，還順手把施工手冊、工安規範、材料清單都補齊，甚至還畫了安全流程圖。這篇就來完整總結今天的協作，至少兩千字，讓我回頭看時知道自己跟 AI 一起幹了什麼。

一、今天的主角：協作紀錄

整天的主戰場，就是那份協作紀錄。裡面記錄了我跟 Codex 來回拉扯的過程——有時候我出需求，它立馬拋一版；有時候它腦補太多，我得毒舌砍掉重練。整體來說，這不是單向生成，而是一種「一人帶腦、一人帶鍵盤」的協作模式。

從紀錄裡，可以看出幾個關鍵節奏：

1. 先把地基鋪好

   • 我們先產出了一份 AGENTS.md，裡面訂下整個 repo 的基本規範：專案結構、Makefile 指令、程式風格、測試流程、Pull Request 規範、安全提示 。
   • 這像是工地的安全守則，確保以後大家不會在施工現場亂丟垃圾。

2. 需求文件進化論

   • requirement.md 被大幅強化。
   • 原本的需求只是一個草稿，今天加上了完整的使用者故事（US-001～US-008），甚至還列了 Acceptance Criteria。
   • 最關鍵的 US-001（布建流程）被拆開深入，衍生出一堆實體文件、API 規格、時序圖，從故事變成能執行的設計。

3. 補齊 API 契約

   • 我們把布建 API 寫進 provisioning-api.md，定義了 POST /internal/v1/provisioning/notification-keys，包含 Request/Response 結構、驗證規則、錯誤碼。
   • 同時也完成了 notification-api.md，涵蓋訊息發送、排程、查詢、目的地管理等功能。

4. 資料與流程模型

   • entities.md：定義了布建相關的核心實體，例如 ProvisionPayloadLog, NotificationKeyProfile, DestinationGrant, SecretDeliveryTicket 等，還有它們的關聯圖。
   • us-001-sequence.md：畫了一張漂亮的時序圖，把外部系統送進來的 Payload → 驗證 → 建立 Key → 授權 → 回傳 Token 的流程完整串起來。

二、協作方式：五步走

今天的過程，其實可以總結成五個步驟。

Step 1：先調研，再動工

我先翻過一些典型的需求範例，觀察「好文件」長怎樣。然後整理出自己專案需要的元素，再丟給 Codex。這一步避免了「直接開工，結果產出四不像」的窘境。

Step 2：讓 AI 生一版草稿

Codex 的強項就是「快」，一丟需求，它立刻吐出一份初稿。雖然初稿常常太理想化，像是「系統應具備高可用性」這種廢話也寫進去，但至少有個骨架。

Step 3：人工 Review，毒舌上線

這是我最喜歡的環節。盯著 AI 的產出，我會開始挑刺：

• 這裡 Acceptance Criteria 不夠具體，要加數字。
• 那裡 API 沒有例子，實在不行。
• 整份文件沒有提到錯誤處理，這怎麼上線？

挑完之後，再把需求丟回去，請 Codex 幫忙補。

Step 4：反覆打磨，文件越來越厚

這個循環至少跑了三四次：

• 使用者故事逐漸具體。
• 功能需求從「會發訊息」變成「支援文字、附件、Adaptive Card；支援批次、排程、廣播」。
• API 文件從只有路徑名稱，變成有完整的 Request/Response JSON 與錯誤碼對照表。

到這裡，需求文件已經從「看不懂」變成「拿去可以真的寫程式」。

Step 5：分拆模組，拉藍圖

最後，整個需求被拆開成不同模組：

• 布建 API：專責接收外部審核通過後的資料。
• 訊息 API：處理所有發送、排程與查詢。
• 資料模型：定義各種實體與關聯，確保 DB 設計有依據。
• 時序圖：把故事變成一個流程，讓人一眼就懂。

三、產出成果：今天的文件大合唱

到一天結束，我們手上已經有了一份完整的「文件家族」。

1. AGENTS.md

   • Repository Guidelines，等同於工地安全規範 。

2. 需求文件 requirement.md

   • 使用者故事 US-001～US-008，全都加了 Acceptance Criteria。
   • 功能需求、非功能需求、API 契約、資料模型、架構圖一應俱全。

3. API 文件

   • Provisioning API：處理布建，定義了 Payload 結構、驗證規則、錯誤處理。
   • Notification API：支援訊息即時發送、排程、查詢、目的地管理。

4. 領域模型

   • Entities：拆解了布建流程中需要的資料表與物件，還附 ER 圖。
   • Sequence：從外部系統呼叫到交付 Token 的完整時序圖。

四、心得：AI 真的是個會加班的小助理

回顧今天，最大的感觸是：AI 不是產品經理，也不是架構師，但它是超快的「文件工人」。

• 我需要範例，它三秒鐘給我一版。
• 我挑毛病，它不會翻桌，馬上改。
• 它不嫌重複，我叫它再補一份詳細表格，它就乖乖加上去。

不過，決策與驗證還是得人來做。例如：

• 目的地驗證要不要自動同步 Teams ID？這就是還沒解決的 open issue。
• API Key 的補發流程要怎麼做？要不要支援 bulk provisioning？這些都還需要 workshop 決議。

五、明日計畫：從文件走向程式

今天的產出堪稱是「藍圖齊全」，但還沒下手寫程式。明天的計畫是：

1. 根據文件定義，開始實作布建 API 的第一個 endpoint。
2. 把資料模型轉成 migration script，建好第一版 DB。
3. 嘗試用 pytest 跑一個簡單的 integration 測試，驗證 API 能正確回應。

六、結語：從草圖到藍圖，工地準備正式開張

第七天，算是這場鐵人賽的第一個「文件高峰」。
今天不只是把需求寫清楚，更把它拆解成 API、模型、流程，一份份文件像磚塊堆起來，搭成了可施工的藍圖。

我最大的體悟是：文件不是浪費時間，而是省時間的工具。

• 沒文件，程式碼全靠腦補，最後 debug 折磨自己。
• 有文件，程式碼只要照著做，少了很多爭議。

所以，雖然今天我打字比平常還累，但換來的收穫更大：
明天開始，真正的工事要開動了。 🚀